<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>5 - Building the System from Source</title>
<link rev= "made" href= "mailto:www@openbsd.org">
<meta name= "resource-type" content= "document">
<meta name= "description"   content= "the OpenBSD FAQ page">
<meta name= "keywords"      content= "openbsd,faq">
<meta name= "distribution"  content= "global">
<meta name= "copyright"     content= "This document copyright 1998-2007 by OpenBSD.">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
</head>

<body bgcolor= "#ffffff" text= "#000000">
<!-- Passes validator.w3.org.  Please keep it this way -->

<a href="../index.html">
<img alt="[OpenBSD]" height=30 width=141 src="../images/smalltitle.gif" border="0">    
</a>
<p>
<font color= "#0000e0">
<a href= "index.html">[FAQ Index]</a>
<a href= "faq4.html">[To Section 4 - Installation Guide]</a>
<a href= "faq6.html">[To Section 6 - Networking]</a>
</font>

<h1><font color="#e00000">5 - Building the System from Source</font></h1>
<hr>

<p>
<h3>Table of Contents</h3>
<ul>
<li><a href="#Flavors">5.1 - OpenBSD's Flavors</a>
<li><a href="#WhySrc">5.2 - Why should I build my system from source?</a>
<li><a href="#Bld">5.3 - Building OpenBSD from source</a>
<ul>
  <li><a href="#BldOverview">5.3.1 - Overview</a>
  <li><a href="#BldBinary">5.3.2 - Install or upgrade to closest
    available binary</a>
  <li><a href="#BldGetSrc">5.3.3 - Fetching the appropriate source
    code</a>
  <li><a href="#BldKernel">5.3.4 - Building the kernel</a>
  <li><a href="#BldUserland">5.3.5 - Building userland</a>
</ul>
<li><a href="#Release">5.4 - Building a release</a>
<li><a href="#Xbld">5.5 - Building X</a>
<li><a href="#Why">5.6 - Why do I need a custom kernel?</a>
<li><a href="#Options">5.7 - Building a custom kernel</a>
<li><a href="#BootConfig">5.8 - Boot-time configuration</a>
<li><a href="#config">5.9 - Using config(8) to change your kernel</a>
<li><a href="#VerboseBoot">5.10 - Getting more verbose output during
  boot</a>
<li><a href="#buildprobs">5.11 - Common problems, tips and questions
  when compiling and building</a>
   <ul>
   <li><a href="#sig11">5.11.1 - The build stopped with a "Signal 11" error</a>
   <li><a href="#snake">5.11.2 - "make build" fails with "cannot open output
      file snake: is a directory"</a>
   <li><a href="#ProbIPv6">5.11.3 - My IPv6-less system doesn't work!</a>
   <li><a href="#ProbObj">5.11.4 - Oops! I forgot to make the <tt>/usr/obj</tt>
      directory first!</a>
   <li><a href="#ProbObjPt">5.11.5 - Put <tt>/usr/obj</tt> on its own
     partition</a>
   <li><a href="#ProbSKIPDIR">5.11.6 - How do I not build parts of the
     tree?</a>
   <li><a href="#ProbMoreInfo">5.11.7 - Where can I learn more about the 
     build process?</a>
   <li><a href="#NoSnaps">5.11.8 - I didn't see any snapshots on the FTP
     site. Where did they go?</a>
   <li><a href="#NewCompiler">5.11.9 - How do I bootstrap a newer version
     of the compiler (<i>gcc</i>)?</a>
   <li><a href="#UpdateEtc">5.11.10 - What is the best way to update
     <tt>/etc</tt>, <tt>/var</tt>, and <tt>/dev</tt>?</a>
   <li><a href="#Hierarchy">5.11.11 - Is there an easy way to make all
     the file hierarchy changes?</a>
   <li><a href="#ProbXComp">5.11.12 - Can I cross-compile?  Why not?</a>
   </ul>
</ul>
<hr>
<br>


<a name="Flavors"></a>
<h2>5.1 - OpenBSD's Flavors</h2>
<!-- XXXversion - revise doodle -->
There are three "flavors" of OpenBSD:
<ul>
<li><b>-release:</b> The version of OpenBSD shipped every six months on CD.
<li><b>-stable:</b>  Release, plus patches considered critical to security
    and reliability.
<li><b>-current:</b> Where new development work is presently being done,
    and eventually, it will turn into the next release.
</ul>

Graphically, the development of these flavors looks something like
this:

<blockquote>
<pre>
       ,------o-----------o----X                    4.0 Stable
       |      .           .
       |      .    ,------o---------o----X          4.1 Stable
       |      .    |      .         .
       |      .    |      .    ,----o----------o--&gt; 4.2 Stable
       |      .    |      .    |    .          .
       |      .    |      .    |    .    ,-----o--&gt; 4.3 Stable
       |      .    |      .    |    .    |     .
       |      .    |      .    |    .    |     .
 --&gt;4.0Rel-----&gt;4.1Rel-----&gt;4.2Rel-----&gt;4.3Rel----&gt; Current 

          Time ---&gt;
</pre>
</blockquote>

<p>
<i>-Current</i> is where active development work is done, and eventually,
it will turn into the next <i>-release</i> of OpenBSD.
Every six months, when a new version of OpenBSD is released,
<i>-current</i> is tagged, and becomes <i>-release</i>: a frozen point
in the history of the source tree.
Each <i>-release</i> is never changed; it is what
is on the <a href="../orders.html">CDs</a> and 
<a href="../ftp.html">FTP servers</a>.

<p>
<i>-Stable</i> is based on <i>-release</i>,
and is a branch from the main development path of OpenBSD.
When very important fixes are made to <i>-current</i>, they are
"back ported" (merged) into the <i>-stable</i> branches;
because of this, <i>-stable</i> is also known as the 
"<i>patch branch</i>."
In the above illustration, the vertical dotted lines denote bug
fixes being incorporated into the <i>-stable</i> branches.  You will
also note that in the above example, the <i>4.0-stable</i> branch came
to an end with <i>4.2-release</i>, and the <i>4.1-stable</i> branch came
to an end with <i>4.3-release</i> -- old releases are typically supported
up to two
releases back.  It takes resources and time to support older versions,
while we might like to provide ongoing support for old releases, we
would rather focus on new features.  The <i>-stable</i> branch is, by
design, very easy to build from <i>-release</i> of the same version
(i.e., going from <i>4.3-release</i> to <i>4.3-stable</i>).

<p>
The <i>-stable</i> branch is <i>-release</i> plus patches found on the
<a href="../errata.html">errata page</a>.
The operation of <i>-stable</i> is the same as the <i>-release</i> it is
based on.
If the <a href="http://www.openbsd.org/cgi-bin/man.cgi">man pages</a>
have to change, it probably won't go into <i>-stable</i>.
In other words, new device support and new features will NOT be added to
<i>-stable</i>.

<p>
It is worth pointing out that the name "<i>-stable</i>" is not intended
to imply that <i>-current</i> is unreliable.
Rather, <i>-current</i> is changing and evolving, whereas the operation
and APIs
of <i>-stable</i> are not going to change, so you shouldn't have to relearn
your system or change any configuration files, or have any problem adding
additional applications to your system.

<p>
In fact, as our hope is to continually improve OpenBSD, the goal is that
<i>-current</i> should be more reliable, more secure, and of course,
have greater features than <i>-stable</i>.
Put bluntly, the "best" version of OpenBSD is <i>-current</i>.

<p>
Warning: <i>-current</i> is a moving target.
It changes minute by minute,
and may well change several times in the time it takes to retrieve the
source code.
While the developers work hard to ensure that the system always compiles
and that there are no major bugs, it is entirely possible to get the
<i>-current</i> source and have it fail to compile, whereas five minutes
later everything will be just fine.
There are also flag days and major system changes
that the developers navigate with one-time tools,
which mean that source-based updating is not possible.
<b>If you are not prepared to deal with this, stay away from
<i>-current</i>.</b>

<p>
Most users should be running either <i>-stable</i> or <i>-release</i>.
That being said, many people do run <i>-current</i> on production
systems, and it is important that some people do so to identify bugs and
test new features.  However, if you don't know how to properly describe,
diagnose and deal with a problem, don't tell yourself (or anyone else)
that you are "helping the project" by running <i>-current</i>.  "It
didn't work!" is not a <a href="../report.html#bugtypes">useful bug
report</a>.  "The recent changes to the pciide driver broke
compatibility with my Slugchip-based IDE interface, dmesg of working and
broken systems follow..." might be a useful report.

<p>
There are times when "normal" users may wish to live on the cutting
edge and run <i>-current</i>. The most common reason is that the user 
has a device
which is not supported by <i>-release</i> (and thus, not <i>-stable</i>),
or wishes to use a new feature of the <i>-current</i>.  In this case, the
choice may be either <i>-current</i> or not using the device, and
<i>-current</i> may be the lesser evil.  However, one should not expect
hand-holding from the developers.

<h3>Snapshots</h3>
Between formal releases of OpenBSD, <i>snapshots</i> are made available
through the <a href="../ftp.html">FTP sites</a>.  As the name implies,
these are builds of whatever code is in the tree at the instant the
builder grabbed a copy of the code for that particular platform.
Remember, on some platforms, it may be DAYS before the snapshot build
is completed and put out for distribution.  There is no promise that the
snapshots are completely functional, or even install.  Often, a change
that needs to be tested may trigger snapshot creation.  Some
platforms have snapshots built on an almost daily basis, others will be
much less frequent.  If you desire to run <i>-current</i>, a recent
snapshot is often all you need, and upgrading to a snapshot is a
required starting point before attempting to build <i>-current</i>
from source.

<p>
It is sometimes asked if there is any way to get a copy of exactly the
code used to build a snapshot.  The answer is no.  First, there is no
significant benefit to this.  Second, the snapshots are built as
desired, as time permits, and as resources become available.  On fast
platforms, several snapshots may be released in one day.  On
slower platforms, it may take a week or more to build a snapshot.
Providing tags or markers in the source tree for each snapshot would be
quite impractical.
Third, snapshots often contain experimental code that isn't yet
committed to the tree.

<h3>Upgrade vs. Update</h3>
You will often see references to "upgrading" and "updating" OpenBSD
installs.  
Even though these words have similar meanings, they are used slightly
differently in OpenBSD.

<p>
<b>Upgrading</b> is the process of installing a newer version of 
OpenBSD, with new functionality.
For example, going from v4.2 to v4.3, or going from the June 12th
snapshot to the June 20th snapshot.
When upgrading, you will typically have to consult either
<a href="current.html">Following -current</a> or the
<a href="upgrade43.html">Upgrade guide</a> (when changing releases)
to make the changes required to run the upgraded version of OpenBSD.

<br>
<b>Updating</b> is the process of applying patches to a system to
improve the operation WITHOUT changing the basic functionality or binary
compatibility. 
This is typically done by following the    
<a href="faq10.html#Patches">source patching process</a> or by following
the <a href="../stable.html">stable process</a>.
When you "update" your system, it goes from a <i>-release</i> to a
<i>-stable</i> (or patched <i>-release</i>) of the same release version,
for example, 4.3-release to 4.3-stable.
You may then later update it to a newer <i>-stable</i> of the same
release version.
The update process is typically very painless, as no <tt>/etc</tt>
files or other system configurations need to be changed.

<p>
So, you may install a system (for example, 4.2-release) from CD, then 
update it to 4.2-stable a few times, then upgrade it to 4.3-release
from CD, and update that a few times before upgrading it again to the
next release.

<h3>Keeping Things in Sync</h3>
It is important to understand that OpenBSD is an Operating System, 
intended to be taken as a whole, not a kernel with a bunch of utilities
stuck on.  You must make sure your kernel, "userland" (the supporting
utilities and files) and <a href="faq15.html#Ports"><tt>ports</tt></a> tree
are all in sync, or unpleasant things will happen.  Said another way
(because people just keep making the error), you can not run brand new
<tt>ports</tt> on a month old system, or rebuild a kernel from <i>-current</i>
source and expect it to work with a <i>-release</i> userland.  Yes,
this does mean you need to upgrade your system if you want to run a new 
program which was added to the ports tree today.  Sorry,
but again, OpenBSD has limited resources available.

<p>
One should also understand that the upgrade
process is supported in <b>only one direction: from older to newer</b>,
and from <i>-stable</i> to <i>-current</i>.  You can not run
<i>4.3-current</i> (or a snapshot), then decide you are living too
dangerously, and step back to <i>4.3-stable</i>.  You are on your own if
you choose any path other than the supported option of reloading your
system from scratch, do not expect assistance from the OpenBSD
development team.

<p>
Yes, this does mean you should think long and hard before committing
yourself to using <i>-current</i>.

<a name="WhySrc"></a>
<h2>5.2 - Why do I need to compile the system from source?</h2>
Actually, you very possibly do not.

<p>
Some reasons why NOT to build from source:
<ul>
<li>Compiling your own system as a way of upgrading it is not supported.
<li>You will NOT get better system performance by compiling your own system.
<li>Changing compiler options is more likely to break your system than
to improve it.
</ul>

Some reasons why you might actually wish or need to build from source:
<ul>
<li>Test or develop new features.
<li>Compiling the system puts a lot of stress on the computer, it can be
a way to make sure the system you just put together or acquired is
actually in pretty good operational condition.
<li>You wish to follow the <a href="../stable.html">stable branch.</a>
<li>You wish to make a highly customized version of OpenBSD for some
special application.
</ul>

<p>
The OpenBSD team puts out new snapshots based on <i>-current</i> code on
a very regular basis for all platforms.
It is likely this will be all you need for running <i>-current</i>.

<p>
The most common reason to build from source is to follow the
<i>-stable</i> branch, where building from source is the only supported
option.

<a name="Bld"></a>
<h2>5.3 - Building OpenBSD from source</h2>

<a name="BldOverview"></a>
<h3>5.3.1 - Overview of the building process</h3>

Building OpenBSD from source involves a number of steps:
<ul>
<li><a href="#BldBinary">Upgrading to the closest available binary.</a>
<li><a href="#BldGetSrc">Fetching the appropriate source code.</a>
<li><a href="#BldKernel">Building the new kernel and booting from it.</a>
<li><a href="#BldUserland">Building "userland" ("make build").</a>
</ul>

There are a couple additional steps that some users may wish to perform, 
depending on the purpose of the build and if X is installed:
<ul>
<li><a href="#Release">Building a "release".</a>
<li><a href="#Xbld">Building X.</a>
</ul>


<a name="BldBinary"></a>
<h3>5.3.2 - Install or Upgrade to closest available binary</h3>

The first step in building from source is to make sure you have the
closest available binary installed.

Use this table to look at where you are, where you wish to go, and what binary
you should start with:

<p>
<table border="1" style="empty-cells: show;">
<tr>
  <td><b>You are at</b></td> <td><b>Goal</b></td>
  <td><b>Binary upgrade to</b></td> <td><b>then ...</b></td>
</tr>
<tr>
  <td> Old -release </td> <td> New release </td> <td> Newest release </td>
  <td> Done! </td>
</tr>
<tr>
  <td> -release </td> <td> -stable </td> <td> Newest release </td>
  <td>Fetch &amp; build <i>-stable</i></td>
</tr>
<tr>
  <td> Old -stable</td> <td> -stable </td> <td> Newest release </td>
  <td>Fetch &amp; build <i>-stable</i></td>
</tr>
<tr>
  <td> -release </td> <td> -current </td> <td> Latest Snapshot </td>
  <td> (optional) Fetch &amp; build <i>-current</i>
</tr>
<tr>
  <td> Old -current </td> <td> -current </td> <td> Latest Snapshot </td>
  <td> (optional) Fetch &amp; build <i>-current</i>
</tr>
</table>

<p>
It is recommended that you install the binary by using the "Upgrade" 
option of the install media.
If that is not possible, you can also unpack the binaries as described
<a href="upgrade43.html">here</a>.
Regardless, you must do the entire upgrade process, including creating 
any users or other <tt>/etc</tt> directory changes needed.


<a name="BldGetSrc"></a>
<h3>5.3.3 - Fetching the appropriate source code</h3>
OpenBSD source is managed using the
<a href="http://ximbiot.com/cvs/cvshome/">CVS</a>
version control system, and
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvs&amp;sektion=1">cvs(1)</a>
is used to pull a copy of the desired source to your local machine
for compilation. 
This can be done by using an <a href="../anoncvs.html">AnonCVS</a>
server (a machine holding a publicly accessible copy of the entire CVS
repository used by the OpenBSD project) or from a local CVS repository
you maintain using the
<a href="../cvsup.html">CVSup</a>, or 
<a href="../cvsync.html">CVSync</a> programs available as
<a href="faq15.html#PkgMgmt">packages</a>.
CVSup can also be used in a "checkout" mode, but that will not be
covered here.
If you have multiple machines you wish to maintain source code trees on,
you may find it worth having a local CVS repository, created and maintained
using CVSup or CVSync.

<p>
After deciding which <a href="../anoncvs.html">AnonCVS server</a> you
wish to use, you must "checkout" the source tree, after that, you then
maintain the tree by running "updates", to pull updated files to your
local tree.

<p>
The
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvs&amp;sektion=1">CVS(1)</a>
command has many options, some of them are <i><b>required</b></i> to
checkout and update a useful tree.
Other commands can cause a broken tree.
Following and understanding directions here is important.

<p>
<b>Following <i>-current</i></b><br>
<blockquote>
In this case, we will assume we are using a public AnonCVS 
server, <b>anoncvs@anoncvs.example.org:/cvs</b>.
We will also assume you are using 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=sh&amp;sektion=1">sh(1)</a>
as your command shell, if you are using a different shell, you will have to
adjust some of these commands.

<p>
To checkout a <i>-current</i> CVS src tree, you can use the following:

<pre>
    # <b>cd /usr</b>
    # <b>export CVSROOT=anoncvs@anoncvs.example.org:/cvs</b>
    # <b>cvs -d$CVSROOT checkout -P src</b>
</pre>

<p>
Once you have a tree, you can update it at a later time:
<pre>
    # <b>cd /usr/src</b>
    # <b>export CVSROOT=anoncvs@anoncvs.example.org:/cvs</b>
    # <b>cvs -d$CVSROOT up -Pd</b>
</pre>
</blockquote>

<!-- XXXrelease -->
<b>Following <i>-Stable</i></b><br>
<blockquote>
If you wish to check out an alternative "branch" of the tree, such as
the <i>-stable</i> branch, you will use the "<tt>-r</tt>" modifier to
your checkout:
<pre>
    # <b>cd /usr</b>
    # <b>export CVSROOT=anoncvs@anoncvs.example.org:/cvs</b>
    # <b>cvs -d$CVSROOT checkout -rOPENBSD_4_3 -P src</b>
</pre>

This will pull the src files from the OPENBSD_4_3 branch, which is also
known as the "Patch branch" or "<a href="../stable.html">-stable</a>".
You would update the code similarly:
<pre>
    # <b>cd /usr/src</b>
    # <b>export CVSROOT=anoncvs@anoncvs.example.org:/cvs</b>
    # <b>cvs -d$CVSROOT up -rOPENBSD_4_3 -Pd</b>
</pre>

Actually, CVS is nice enough to stick a "Tag" in the checked out file
system, so you don't have to remember the "<tt>-rOPENBSD_4_3</tt>" part
of the command line, it will remember this until you explicitly clear
them or set a new tag by using the "<tt>-A</tt>" option to
"<tt>update</tt>".
However, it is probably better to provide too much info in your CVS
command lines than too little.
</blockquote>

<p>
While only the "<tt>src</tt>" tree has been shown so far, you will do the
same steps for "<tt>xenocara</tt>" and "<tt>ports</tt>".
As all parts of OpenBSD must be kept in sync, all trees you use should be
checked out and updated at the same time.
You can combine the checkouts into one line (<i>-stable</i> shown):
<pre>
    # <b>export CVSROOT=anoncvs@anoncvs.example.org:/cvs</b>
    # <b>cd /usr</b>
    # <b>cvs -d$CVSROOT checkout -rOPENBSD_4_3 -P src ports xenocara</b>
</pre>

However, updates must be done directory-by-directory.

<p>
At this point, whether you followed <i>-stable</i> or <i>-current</i>
you should have a usable source tree.
Be very careful which tree you grab -- it is easy to try to compile 
<i>-current</i> when aiming for <i>-stable</i>.

<h4>Pre-loading the tree: <tt>src.tar.gz, sys.tar.gz</tt></h4>
While you can download the entire source tree from an AnonCVS server,
you can often save a lot of time and bandwidth by "pre-loading" your
source tree with the source files from either the OpenBSD CD or from an
FTP server.
This is particularly true if you are running
<a href="../stable.html"><i>-stable</i></a>, as relatively few files change
between this version and the <i>-release</i> it is based on.

<p>
To extract the source tree from the CD to <i>/usr/src</i> (assuming the CD is
mounted on /mnt):
<pre>
    # <b>cd /usr/src; tar xzf /mnt/src.tar.gz</b>
    # <b>cd /usr; tar xzf /mnt/xenocara.tar.gz</b>
    # <b>cd /usr; tar xzf /mnt/ports.tar.gz</b>
</pre>

The source files available for download from the FTP servers are separated into two
files to minimize the download time for those wishing to work
with only one part of the tree.  The two files are <tt>sys.tar.gz</tt>,
which contains the files used to create the kernel, and <tt>src.tar.gz</tt>
which contains all the other "userland" utilities except the ports tree
and the X11 sources.
In general, however, you will usually want both of them installed.
Assuming the downloaded files, <tt>src.tar.gz</tt> and
<tt>sys.tar.gz</tt>, are in <tt>/usr</tt>:
  
<pre>
    # <b>cd /usr/src</b>
    # <b>tar xzf ../sys.tar.gz</b>
    # <b>tar xzf ../src.tar.gz</b>
    # <b>cd /usr</b>
    # <b>tar xzf xenocara.tar.gz</b>
    # <b>tar xzf ports.tar.gz</b>
</pre>

<p>
Not all people will wish to unpack all the file sets, but as the system
must be kept in sync, you will generally need to set up all parts of the tree.


<a name="CVSTips"></a>
<h4>Common CVS tips</h4>

As indicated earlier, some options are mandatory to get a valid
<tt>src</tt> tree in OpenBSD.
The "<tt>-P</tt>" option above is one of those: It "prunes" (removes)
directories that are empty.
Over the years, directories have been created and deleted in the OpenBSD
source tree, and sometimes the names of old directories are currently
used as file names.
Without the "<tt>-P</tt>" option, your newly checked-out tree WILL NOT
successfully compile.

<p>
Much the same with the <tt>-d</tt> option on the 'update' command -- it
creates new directories that may have been added to the tree since your
initial checkout.
To get a successful update, you must use the <tt>-Pd</tt> options.

<p>
Experienced CVS users may wonder why the CVSROOT was specified and 
used in this example, as cvs(1) will record the CVS server's location in 
the checked out tree.
This is correct, however there are enough times where one may need to 
override the default anoncvs server, many people recommend <i>always</i>
specifying the repository explicitly.
It is also worth noting that while the CVSROOT environment variable can
be used directly by cvs(1), it is used only if nothing else overrides
it (i.e., cvs(1) would have an error without it), whereas specifying it
in the cvs(1) command line overrides all other values.

<p>
It is often useful to use a <tt>.cvsrc</tt> in your home directory to 
specify defaults for some of these options.
An example <tt>.cvsrc</tt> file:
<pre>
    $ <b>more ~/.cvsrc</b>
    cvs -q -danoncvs@anoncvs.example.org:/cvs
    diff -up
    update -Pd
    checkout -P
</pre>

This file would cause cvs(1) to use the 
<tt>anoncvs@anoncvs.example.org:/cvs</tt> server, suppress usually
unneeded output ("<tt>-q</tt>" is "quiet") for all operations, 
a "cvs up" command defaults to using the <tt>-Pd</tt>,
a "cvs diff" defaults to providing "unified diffs" due to the "<tt>-u</tt>", 
and a "cvs checkout" will use the "<tt>-P</tt>" option.
While this is convenient, if you forget this file exists, or try to run
commands you got used to on a machine without this file, you will have
problems.

<p>
As the source trees consist of large numbers of mostly small files,
turning on <a href="faq14.html#SoftUpdates">soft updates</a> for the
partition the source tree is on will often give significantly better
performance.


<a name="BldKernel"></a>
<a name="Building"></a>  <!-- Old tag -->
<h3>5.3.4 - Building the kernel</h3>
We will assume you wish to build a standard (GENERIC or GENERIC.MP)
kernel here.
Normally, this is what you want to do.
Do <i>not</i> consider building a custom kernel if you have not mastered
the standard building process.

<p>
Obviously, the kernel is a VERY hardware dependent portion of the
system.
The source for the kernel is in the <tt>/usr/src/sys</tt> directory.
Some parts of the OpenBSD kernel code are used on all platforms, others
are very specific to one processor or one architecture.
If you look in the <tt>/usr/src/sys/arch/</tt> directory, you may see
some things that look a little confusing -- for example, there are
<tt>mac68k</tt>, <tt>m68k</tt> and <tt>mvme68k</tt> directories.
In this case, the mvme68k and mac68k systems both use the same
processor, but the machines they are based on are very different, and
thus require a very different kernel (there is much more to a computer's
design than its processor!).
However, parts of the kernel are common, those parts are kept in the
m68k directory.
If you are simply building a kernel, the base architecture directories 
like <tt>m68k</tt> are not anything for you to worry about, you will
be working exclusively with the "compound architecture" directories, 
such as <tt>mvme68k</tt>.

<p>
Kernels are built based on <a href="#Options">kernel configuration
files</a>, which are located in the
<tt>/usr/src/sys/arch/&lt;<i>your platform</i>&gt;/conf</tt> directory.
Building the kernel consists of using the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=config&amp;sektion=8">config(8)</a>
program to create and populate a kernel compile directory, which will
end up in
<tt>/usr/src/sys/arch/&lt;<i>your platform</i>&gt;/compile/&lt;<i>KernelName</i>&gt;</tt>.
For this example, we will assume you are using the i386 platform:

<blockquote><pre>
# <b>cd /usr/src/sys/arch/i386/conf</b>
# <b>config GENERIC</b>
# <b>cd ../compile/GENERIC</b>
# <b>make clean && make depend && make</b>
    <i>[...lots of output...]</i>
# <b>make install</b>
</pre></blockquote>

Replace "<tt>i386</tt>" in the first line with your platform name.
The 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=machine&amp;sektion=1">machine(1)</a>
command can tell you what your platform name is, so an obvious
generalization would be to use the command "<tt>cd
/usr/src/sys/arch/`machine`/conf</tt>" instead on the first line.

<p>
At this point, reboot your machine to activate this new kernel.
Note that the new kernel should be running before the next step, though
if you have followed the <a href="#BldBinary">above</a> advice about upgrading
to the most recent available snapshot, it may not matter as much.  
Sometimes, however, APIs change, and the old kernel will be unable to run 
new applications, but the new kernel will generally support the old ones.

<h4>Variation on above process: Read-only source tree</h4>
Sometimes, you may wish to ensure your <tt>/usr/src/sys</tt> directory
remains untouched.
This can be done by using the following process:

<blockquote><pre>
$ <b>cd <i>/somewhere</i></b>
$ <b>cp /usr/src/sys/arch/i386/conf/GENERIC .</b>
$ <b>config -s /usr/src/sys -b . GENERIC</b>
$ <b>make clean && make depend && make</b>
   ... lots of output ...
</pre></blockquote>

Note that you can build a kernel without root access, but you must have
root to install the kernel.


<a name="BldUserland"></a>
<h3>5.3.5 - Building the userland</h3>

There is a specific process used by OpenBSD.
Processes used on other OSs you may have been familiar with will most likely
not work on OpenBSD, and will get you laughed at when you ask why.

<p>
<ul>
<li>Clear your <tt>/usr/obj</tt> directory and rebuild symbolic links:
<blockquote><pre>
# <b>rm -rf /usr/obj/*</b>
# <b>cd /usr/src</b>
# <b>make obj</b>
</pre></blockquote>

Note that the use of the <tt>/usr/obj</tt> directory is mandatory.
Failing to do this step before building the rest of the tree will likely
leave your <tt>src</tt> tree in bad shape.

<p>
<li>Make sure all the appropriate directories are created.
<blockquote><pre>
# <b>cd /usr/src/etc && env DESTDIR=/ make distrib-dirs</b>
</pre></blockquote>

<p>
<li>Build the system:
<blockquote><pre>
# <b>cd /usr/src</b>
# <b>make build</b>
</pre></blockquote>
This compiles and installs all the "userland" utilities in the
appropriate order.
This is a fairly time consuming step -- a very fast machine may be able
to complete it in well under an hour, a very slow machine may take many
days.
When this step is complete, you have newly compiled binaries in place
on your system.

<p>
<li><b>If building <i>-current</i>:</b> Update <tt>/dev</tt> and
<tt>/etc</tt>, with the changes listed in
<a href="current.html">current.html</a>.
If following -stable after a proper <a href="upgrade43.html">upgrade
process</a> or a install of the <a href="#BldBinary">proper starting
binary</a>, this step is not needed or desired.

</ul>


<a name="Release"></a>
<a name="BldRelease"></a> <!-- old tag -->
<h2>5.4 - Building a Release</h2>
<h3>What is a "release", and why would I want to make one?</h3>
A release is the complete set of files that can be used to install OpenBSD
on another computer.
If you have only one computer running OpenBSD, you really don't have any
reason to make a release, as the <a href="#Bld">above</a> build process
will do everything you need.
An example use of the release process would be to build <i>-stable</i>
on a fast machine, then make a release to be installed on all your other
machines in your office.

<p>
The release process uses the binaries created in the <tt>/usr/obj</tt> 
directory in the building process above, so you must successfully
complete the build first, and nothing must disturb the <tt>/usr/obj</tt>
directory.
A time where this might be a problem is if you use a
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=mount_mfs&amp;sektion=8">memory
disk</a> as your <tt>/usr/obj</tt> for a little extra performance in the
build process, you would not want to reboot the computer between the "build" 
and "release" steps!

<p>
The release process requires two work directories, which we will call 
DESTDIR and RELEASEDIR.
All the files that are part of a "clean" OpenBSD install will be copied
to their proper place within the DESTDIR.
They will then be tar(1)ed up and placed in the RELEASEDIR.
At the end of the process, RELEASEDIR will hold the completed OpenBSD
release.
The release process will also use the <tt>/mnt</tt> location, so this 
should not be used by anything while the release process is running.
For the purpose of example, we will use the DESTDIR of
<tt>/usr/dest</tt> and the RELEASEDIR of <tt>/usr/rel</tt>.


<p>
The release process involves a couple utilities which are not in the 
base OpenBSD system, crunch and crunchgen(1), which are used to create
a single executable file made up of many individual binaries.
The name this single executable file is invoked by determines which 
component binary is run.
This is how a number of individual program files are squeezed into 
the ramdisk kernel that exists on boot floppies and other boot media.
<i>These utilities must be built before the release process is
started.</i>
They only need to be built and installed once, but as people often
forget this step, and these programs build quickly, some people opt to
just build crunch and crunchgen every time as part of the script they
use to make a release.

<p>
You must have root privileges to make a release.

<p>
<h3>Doing a release</h3>

First, if it has not been done on this machine, build crunch and
crunchgen:
<blockquote><pre>
# <b>cd /usr/src/distrib/crunch && make obj depend all install</b>
</pre></blockquote>

Now, we define our DESTDIR and RELEASEDIR environment variables:
<blockquote><pre>
# <b>export DESTDIR=/usr/dest</b>
# <b>export RELEASEDIR=/usr/rel</b>
</pre></blockquote>

We now clear the DESTDIR and create the directories if needed:
<blockquote><pre>
# <b>test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}.old && rm -rf ${DESTDIR}.old &</b>
# <b>mkdir -p ${DESTDIR} ${RELEASEDIR}</b>
</pre></blockquote>

RELEASEDIR does not normally need to be empty before starting the release
process, however, if there are changes in the release files or their names, 
old files may be left laying around.
You may wish to also erase this directory before starting.

<p>
We now make the release itself:
<blockquote><pre>
# <b>cd /usr/src/etc</b>
# <b>make release</b>
</pre></blockquote>

After the release is made, it is a good idea to check the release to
make sure the tar files are matching what is in the DESTDIR.
The output of this step should be very minimal.

<blockquote><pre>
# <b>cd /usr/src/distrib/sets</b>
# <b>sh checkflist</b>
</pre></blockquote>

You now have complete and checked release file sets in the RELEASEDIR.
These files can now be used to install or upgrade OpenBSD on other
machines.

<p>
The authoritative instructions on making a release are in
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=release&amp;sektion=8">release(8)</a>.

<p>
Note: if you wish to distribute the resultant files by HTTP for use by
the upgrade or install scripts, you will need to add an "index.txt"
file, which contains the list of all the files in your newly created
release.
<blockquote><pre>
# <b>/bin/ls -1 >index.txt</b>
</pre></blockquote>

<a name="Xbld"></a>
<h2>5.5 - Building X (Xenocara)</h2>
<i>Note: the following instructions are for OpenBSD 4.2 and later.
If you are wishing to build X for 4.1 or before (you should really
<a href="upgrade43.html">upgrade</a>!), you can find the previous
version of these instructions in
<a href="http://www.openbsd.org/cgi-bin/cvsweb/~checkout~/www/faq/faq5.html?rev=1.155&content-type=text/html#Xbld">cvsweb</a></i>.

<p>
Starting with <a href="http://x.org/">X.org v7,</a> X switched to
"modular build" system, splitting the x.org source tree into more than
three hundred more-or-less independent packages.

<p>
To simplify life for OpenBSD users, a "meta-build" called
<a href="http://xenocara.org">Xenocara</a> was developed.
This system "converts" X back into one big tree to be built in one
process.
As an added bonus, this build process is much more similar to the build
process used by the rest of OpenBSD than the previous versions were.

<p>
The official instructions for building X exist in your machine's
<tt>/usr/xenocara/README</tt> file and in
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=release&amp;sektion=8">release(8)</a>.

<h3>Getting source code</h3>
The "usual" location for the xenocara source tree is
<tt>/usr/xenocara</tt>, and the source is stored in the
<tt>xenocara</tt> module in CVS.
So, the checkout process is this:
<blockquote><pre>
$ <b>cd /usr</b>
$ <b>cvs -qdanoncvs@anoncvs.example.org:/cvs checkout -P xenocara</b>
</pre></blockquote>

<h3>Building Xenocara</h3>
For building the standard xenocara tree as supported by OpenBSD,
no external tools are needed.

<blockquote><pre>
# <b>cd /usr/xenocara</b>
# <b>make bootstrap</b>
# <b>make obj</b>
# <b>make build</b>
</pre></blockquote>

If you wish to make actual modifications to the source code, you will
probably need to add several <a href="faq15.html">packages</a>.
Details are in the <tt>/usr/xenocara/README</tt> file.

<h3>Making a release</h3>
This is similar to the main system release process.
After successfully building X, you will define a DESTDIR and RELEASEDIR,
with the same purposes as above.
The RELEASEDIR can be the same directory as the main system RELEASEDIR,
but DESTDIR will be erased and rebuilt in this process.
If done carefully, this is not a problem, but using a separate DESTDIR
may be "safer".

<p>
For this example, we will use a DESTDIR and RELEASEDIR of /usr/dest and
/usr/rel, respectively.
This must be done after the above build process.

<blockquote><pre>
# <b>export DESTDIR=/usr/dest</b>
# <b>export RELEASEDIR=/usr/rel</b>
# <b>test -d ${DESTDIR} && mv ${DESTDIR} ${DESTDIR}- && \</b>
  <b>   rm -rf ${DESTDIR}- &</b>
# <b>mkdir -p ${DESTDIR} ${RELEASEDIR}</b>
# <b>make release</b>
</pre></blockquote>

When this process is completed, you will have a set of release files
in the $RELEASEDIR.

<p>
<a name="Why"></a>
<h2>5.6 - Why do I need a custom kernel?</h2>

<p>
Actually, you probably don't.

<p>
A custom kernel is a kernel built with a configuration file other than 
the provided <tt>GENERIC</tt> configuration file.
A custom kernel can be based on <a href="#Flavors"><i>-release,
-stable</i> or <i>-current</i></a> code, just as a <tt>GENERIC</tt>
kernel can be.
While compiling your own <tt>GENERIC</tt> kernel is supported by the
OpenBSD team, compiling your own custom kernel is <i>not</i>.

<p>
The standard OpenBSD kernel configuration (<tt>GENERIC</tt>) is designed
to be suitable for most people.
More people have broken their system by trying to tweak their
kernel than have improved system operation.
There are some people that believe that you must customize your kernel
and system for optimum performance, but this is not true for OpenBSD.
Only the most advanced and knowledgeable users with the most demanding 
applications need to worry about a customized kernel or system.

<p>
Some reasons you might want or need to build a custom kernel:
<ul>
  <li>You really know what you are doing, and want to shoe-horn
      OpenBSD onto a computer with a small amount of RAM
      by removing device drivers you don't need.
  <li>You really know what you are doing, and wish to remove default
      options or add options which may not have been enabled by default
      (and have good reason to do so).
  <li>You really know what you are doing, and wish to enable experimental
      options.
  <li>You really know what you are doing, and have a special need that is
      not met by <tt>GENERIC</tt>, and
      aren't going to ask why it doesn't work if something goes wrong.
</ul>

<p>
Some reasons why you should not build a custom kernel:
<ul>
  <li>You do not need to, normally.
  <li>You will not get a faster system.
  <li>You are likely to make a less reliable machine.
  <li>You will not get any support from developers.
  <li>You will be expected to reproduce any problem with a <tt>GENERIC</tt>
      kernel before developers take any problem report seriously.
  <li>Users and developers will laugh at you when you break your system.
  <li>Custom compiler options usually do a better job of exposing
      compiler problems than improving system performance.

</ul>

<p>
Removing device drivers may speed the boot process on your system, but
can complicate recovery should you have a hardware problem, and is
very often done wrong.  
Removing device drivers <i>will not</i> make your system run faster by
any noticeable amount, though can produce a smaller kernel.
Removing debugging and error checking can result in a measurable
performance gain, but will make it impossible to troubleshoot a system
if something goes wrong.


<p>
Again, developers will
usually ignore bug reports dealing with custom kernels, unless the
problem can be reproduced in a <tt>GENERIC</tt> kernel as well.
You have been warned.

<p>
<a name="Options"></a>
<h2>5.7 - Building a custom kernel</h2>
It is assumed you have read the <a href="#Why">above</a>, and really
enjoy pain.
It is also assumed that you have a goal that can not be achieved by
either a <a href="#BootConfig">Boot time configuration (UKC>)</a> or
by <a href="#config">config(8)ing a GENERIC kernel</a>.
If both of these are not true, you should stick to using GENERIC.
Really.

<p>
OpenBSD kernel generation is controlled by configuration files, 
which are located in the <tt>/usr/src/sys/arch/<i>&lt;arch&gt;</i>/conf/</tt>
directory by default.  All architectures have a file, <tt>GENERIC</tt>,
which is used to generate the standard OpenBSD kernel for that platform.
There may also be other configuration files which are used to create 
kernels with different focuses, for example, for minimal RAM, diskless
workstations, etc.  

<p>
The configuration file is processed by 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=config&amp;sektion=8">config(8)</a>,
which creates and populates a compilation directory in <tt>../compile</tt>,
on a typical installation, that would be in
<tt>/usr/src/sys/arch/<i>&lt;arch&gt;</i>/compile/</tt>.  config(8) also creates
a <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=make&amp;sektion=1">Makefile</a>,
and other files required to successfully build the kernel.

<p>
Kernel Configuration Options are options that you add to your kernel
configuration that place certain features into your kernel. This allows
you to have exactly the support you want, without having support for
unneeded devices. There are a multitude of options that allow you to
customize your kernel. Here we will go over only some of them, those that
are most commonly used. Check the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=options&amp;sektion=4">options(4)</a>
man page for a complete list of options, and as these change from time
to time, you should make sure you use a man page for the same version of
OpenBSD you are building. You can also check the example configuration
files that are available for your architecture.

<p>
<b>Do not add, remove, or change options in your kernel unless you
actually have a reason to do so!  Do not edit the <tt>GENERIC</tt>
configuration file!!</b>
The only kernel configuration
which is supported by the OpenBSD team is the GENERIC kernel, the
combination of the options in
<tt>/usr/src/sys/arch/&lt;<i>arch</i>&gt;/conf/GENERIC</tt>
and <tt>/usr/src/sys/conf/GENERIC</tt> <i>as shipped by the OpenBSD
team</i> (i.e., NOT edited).  Reporting a problem on a customized kernel
will almost always result in you being told to try to reproduce the
problem with a GENERIC kernel.  Not all options are compatible with
each other, and many options are required for the system to work.  There
is no guarantee that just because you manage to get a custom kernel
compiled that it will actually run.
There is no guarantee that a kernel that can be "config(8)ed" can be
built.

<p>
You can see the platform-specific configuration files here:
<ul>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/alpha/conf/">alpha Kernel Configuration Files </a>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/i386/conf/">i386 Kernel Configuration Files</a>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/macppc/conf/">macppc Kernel Configuration Files</a>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/sparc/conf/">sparc Kernel Configuration Files</a>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/sparc64/conf/">sparc64 Kernel Configuration Files</a>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/vax/conf/">vax Kernel Configuration Files</a>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/hppa/conf/">hppa Kernel Configuration Files</a>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/arch/">Other Arch's</a>
</ul>

<p>
Look closely at these files and you will notice a line near the top
similar to:
<pre>
     include "../../../conf/GENERIC"
</pre>
This means that it is referencing another configuration file, one
that stores platform-independent options.  When creating your kernel
configuration, be sure to look through 
<a href="http://www.openbsd.org/cgi-bin/cvsweb/src/sys/conf/GENERIC">sys/conf/GENERIC</a>. 
<p>
Kernel configuration options should be placed in your kernel
configuration file in the format of:
<blockquote>
<tt>option&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>name</i>
</blockquote>
or
<blockquote><pre>
<tt>option&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt><i>name=value</i> 
</pre></blockquote>

For example, to place option "DEBUG" in the kernel, add a line like this:

<blockquote><pre>
option      DEBUG
</pre></blockquote>

Options in the OpenBSD kernel are translated into compiler preprocessor
options, therefore an option like DEBUG would have the source compiled
with option -DDEBUG, which is equivalent to doing a <tt>#define DEBUG</tt>
throughout the kernel.

<p>
Sometimes, you may wish to disable an option that is already defined,
typically in the "<tt>src/sys/conf/GENERIC</tt>" file.  While you could
modify a copy of that file, a better choice would be to use the
<i>rmoption</i> statement.  For example, if you really wanted to 
disable the in-kernel debugger (<i>not recommended!</i>), you would add
a line such as:
<pre>
     rmoption DDB
</pre>
in your kernel configuration file.  <tt>option DDB</tt> is defined in
<tt>src/sys/conf/GENERIC</tt>, but the above <tt>rmoption</tt> line
deactivates it.

<p>
Once again, please see 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=options&amp;sektion=4">options(4)</a>
for more information about the specifics of these options.  Also note
that many of the options also have their own manual pages -- always read
everything available about an option before adding or removing it from
your kernel.

<p> 
<h3>Building a custom kernel</h3>

In this case, we will build a kernel that supports the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=boca&amp;sektion=4">boca(4)</a>
ISA multi-port serial card.
This card is not in the GENERIC kernel, due to conflicts with other
drivers.

Another common reason to make a custom kernel would be to use RAIDframe,
which is too large to have in the stock kernel.
There are two common ways to make a custom kernel: copy the GENERIC
config file to another name and edit it, or create a "wrapper" file that
"includes" the standard GENERIC kernel and any options you need that
aren't in GENERIC.
In this case, our wrapper file looks like this:
<blockquote><pre>
include "arch/i386/conf/GENERIC"

boca0  at       isa? port 0x100 irq 10     # BOCA 8-port serial cards
pccom* at       boca? slave ?
</pre></blockquote>

The two lines regarding the boca(4) card are copied from the commented
out lines in <tt>GENERIC</tt>, with the IRQ adjusted as needed.
The advantage to using this "wrapper" file is any unrelated changes in
GENERIC are updated automatically with any other source code update.
The disadvantage is one can not remove devices (though in general, that's 
a bad idea, anyway).

<p>
Another way to generate a custom kernel is to make a copy of the
standard <tt>GENERIC</tt>, giving it another name, then editing it as
needed.
The disadvantage to this is later updates to the GENERIC configuration
file have to be merged into your copy, or you have to remake your 
configuration file.

<p>
In either event, after making your custom kernel configuration file,
use config(8) and make the kernel as documented
<a href="#BldKernel">above</a>.


<p>
Full instructions for creating your own custom kernel are in the
<a href= "http://www.openbsd.org/cgi-bin/man.cgi?query=config&amp;sektion=8#EXAMPLES+(kernel">
config(8)</a> man page.


<a name="BootConfig"></a>
<h2>5.8 - Boot-Time Configuration</h2>

<p>
Sometimes when booting your system you might notice that the kernel finds
your device but maybe at the wrong IRQ. And maybe you need to use this
device right away. Well, without rebuilding the kernel you can use
OpenBSD's boot time kernel configuration. This will only correct your
problem for one time. If you reboot, you will have to repeat this
procedure. So, this is only meant as a temporary fix, and you should
correct the problem using <a href="#config">config(8)</a>. Your kernel
does however need <strong>option BOOT_CONFIG</strong> in the kernel, which 
GENERIC does have.

<p>
Most of this document can be found in the man page
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=boot_config&amp;sektion=8">boot_config(8)</a>.

<p>
To boot into the User Kernel Config, or UKC, use the -c option at boot time.

<blockquote><pre>
boot&gt; <strong>boot hd0a:/bsd -c</strong>
</pre></blockquote>

Or whichever kernel it is you want to boot. Doing this will bring up a
UKC prompt. From here you can issue commands directly to the kernel
specifying devices you want to change or disable or even enable.

<p>
Here is a list of common commands in the UKC.

<ul>
<li><tt>add <strong>device</strong></tt> - Add a device through copying another
<li><tt>change <strong>devno | device </strong></tt> - Modify one or more devices
<li><tt>disable <strong>devno | device </strong></tt> - Disable one or more devices 
<li><tt>enable <strong>devno | device </strong></tt> - Enable one or more devices 
<li><tt>find <strong>devno | device </strong></tt> - Find one or more devices
<li><tt>help</tt> - Short summary of these commands
<li><tt>list</tt> - List ALL known devices
<li><tt>exit/quit</tt> - Continue Booting
<li><tt>show <strong>[attr [val]]</strong></tt> - Show devices with an attribute and
  optional with a specified value
</ul>

<p>
Once you have your kernel configured, use <tt>quit</tt> or <tt>exit</tt>
and continue booting.
After doing so, you should make the change permanent in your
kernel image, as described in <a href="#config">Using config(8)
to change your kernel</a>.


<p>
<a name="config"></a>
<h2>5.9 - Using config(8) to change your kernel</h2>
<p>
The <b>-e</b> and <b>-u</b> options with
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=config&amp;sektion=8">config(8)</a>
can be extremely helpful and save wasted time compiling your kernel. The
<b>-e</b> flag allows you to enter the UKC or User Kernel Config on a
running system. These changes will then take place on your next reboot.
The <b>-u</b> flag tests to see if any changes were made to the running
kernel during boot, meaning you used <b>boot -c</b> to enter the UKC
while booting your system.

<p>
The following example shows the disabling of the ep* devices in the
kernel. For safety's sake you must use the <b>-o</b> option which writes
the changes out to the file specified. For example : <strong>config -e
-o bsd.new /bsd</strong> will write the changes to bsd.new. The example
doesn't use the <b>-o</b> option, therefore changes are just ignored,
and not written back to the kernel binary. For more information
pertaining to error and warning messages read the 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=config&amp;sektion=8">config(8)</a>
man page.

<!--XXXver -->
<blockquote><pre>
$ <strong>sudo config -e /bsd</strong>
OpenBSD 4.3 (GENERIC) #698: Wed Mar 12 11:07:05 MDT 2008
    deraadt@i386.openbsd.org:/usr/src/sys/arch/i386/compile/GENERIC
warning: no output file specified
Enter 'help' for information
ukc&gt; ?
        help                            Command help list
        add         dev                 Add a device
        base        8|10|16             Base on large numbers
        change      devno|dev           Change device
        disable     attr val|devno|dev  Disable device
        enable      attr val|devno|dev  Enable device
        find        devno|dev           Find device
        list                            List configuration
        lines       count               # of lines per page
        show        [attr [val]]        Show attribute
        exit                            Exit, without saving changes
        quit                            Quit, saving current changes
        timezone    [mins [dst]]        Show/change timezone
        nmbclust    [number]            Show/change NMBCLUSTERS
        cachepct    [number]            Show/change BUFCACHEPERCENT
        nkmempg     [number]            Show/change NKMEMPAGES
        shmseg      [number]            Show/change SHMSEG
        shmmaxpgs   [number]            Show/change SHMMAXPGS
ukc&gt; <strong>list</strong>
  0 audio* at sb0|sb*|gus0|pas0|sp0|ess*|wss0|wss*|ym*|eap*|eso*|sv*|neo*|cmpci*
|clcs*|clct*|auich*|autri*|auvia*|fms*|uaudio*|maestro*|esa*|yds*|emu* flags 0x0
  1 midi* at sb0|sb*|opl*|opl*|opl*|opl*|ym*|mpu*|autri* flags 0x0
  2 nsphy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr*
|ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e
p*|ep* phy -1 flags 0x0
  3 nsphyter* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|
vr*|ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep
*|ep*|ep* phy -1 flags 0x0
  4 qsphy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr*
|ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e
p*|ep* phy -1 flags 0x0
  5 inphy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr*
|ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e
p*|ep* phy -1 flags 0x0
  6 iophy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr*
|ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e
p*|ep* phy -1 flags 0x0
  7 eephy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr*
|ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e
p*|ep* phy -1 flags 0x0
  8 exphy* at aue*|xe*|ef*|gx*|stge*|bge*|nge*|sk*|ste*|sis*|sf*|wb*|tx*|tl*|vr*
|ne0|ne1|ne2|ne*|ne*|ne*|dc*|dc*|rl*|fxp*|fxp*|xl*|xl*|ep0|ep0|ep0|ep*|ep*|ep*|e
p*|ep* phy -1 flags 0x0
[...snip...]
ukc&gt; <strong>disable ep</strong>
 67 ep0 disabled
 68 ep* disabled
 69 ep* disabled
155 ep0 disabled
156 ep0 disabled
157 ep* disabled
158 ep* disabled
210 ep* disabled
ukc&gt; <strong>quit</strong>
not forced
</pre></blockquote>

<p>
In the above example, all ep* devices are disabled in the kernel and will
not be probed. In some situations where you have used the UKC during boot,
via <b>boot -c</b>, you will need these changes to be written out
permanently. To do this you need to use the <b>-u</b> option.
In the following example, the computer was booted into the UKC and the
wi(4) device was disabled. Since changes made with boot -c are NOT
permanent, these changes must be written out. This example writes the
changes made from boot -c into a new kernel binary bsd.new.

<blockquote><pre>
$ <strong>sudo config -e -u -o bsd.new /bsd</strong>
OpenBSD 4.3 (GENERIC) #698: Wed Mar 12 11:07:05 MDT 2008
    deraadt@i386.openbsd.org:/usr/src/sys/arch/i386/compile/GENERIC
Processing history...
105 wi* disabled
106 wi* disabled
Enter 'help' for information
ukc&gt; <strong>quit</strong>
</pre></blockquote>


<a name="VerboseBoot"></a>
<h2>5.10 - Getting more verbose output during boot</h2>

Getting more verbose output can be very helpful when trying to debug
problems when booting.  If you have a problem wherein your boot floppy
won't boot and need to get more information, simply reboot. When you get
to the &quot;boot&gt;&quot; prompt, boot with boot -c. This will bring you
into the UKC&gt;, then do:

<blockquote><pre>
UKC&gt; <strong>verbose</strong>
autoconf verbose enabled
UKC&gt; <strong>quit</strong>
</pre></blockquote>

<p>
Now you will be given extremely verbose output upon boot.



<p>
<a name="buildprobs"></a>
<h2>5.11 - Common problems, tips and questions when compiling and
building</h2>
Most of the time, problems in the build process are caused by not
following the above directions carefully.
There are occasional real problems with building <i>-current</i> from
the most recent snapshot, but failures when building <i>-release</i> or
<i>-stable</i> are almost always user error.

<p>
Most problems are usually one of the following:
<ul>
<li>Failing to start from the <a href="#BldBinary">appropriate
binary</a>, including attempting to upgrade from source or assuming
a week old snapshot is "close enough".
<li><a href="#BldGetSrc">Checking out</a> the wrong branch of the tree.
<li>Not following the <a href="faq5.html">process</a>.
<li>Trying to <a href="#Why">customize</a> or "optimize" your system.
</ul>

Here are some additional problems you might encounter, however:

<a name="sig11"></a>
<h3>5.11.1 - The build stopped with a "Signal 11" error</h3>

<p>
Building OpenBSD and other programs from source is a task which pushes
hardware harder than most others, making intensive use of CPU, disk and
memory. As a result, if you have hardware which has a problem, the most
likely time for that problem to appear is during a build.  Signal 11
failures are <i>typically</i> caused by hardware problems, very often
memory problems, but can also be CPU, main board, or heat issues.  Your
system may actually be very stable otherwise, but unable to compile
programs.

<p>
You will probably find it best to repair or replace the components that
are causing trouble, as problems may show themselves in other ways in
the future.  If you have hardware which you really wish to use and
causes you no other problem, simply install a snapshot or a release.

<p>
For much more information, see the
<a href="http://www.bitwizard.nl/sig11/">Sig11 FAQ</a>.

<a name="snake"></a>
<h3>5.11.2 - "make build" fails with "cannot open output file snake: is
a directory"</h3>

This is the result of two separate errors: 
<ul>
<li><b>You did not fetch or update your CVS tree properly.</b>  When 
doing a CVS checkout operation, you must use the "<tt>-P</tt>" option,
when you update your source tree with CVS, you must use "<tt>-Pd</tt>"
options to
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=cvs&amp;sektion=1"
>cvs(1)</a>,
as documented <a href="#BldGetSrc">above</a>.
These options make sure new directories are added and removed from the
tree as OpenBSD evolves.

<li><b>You did not properly create the <tt>obj</tt> directory before
your build.</b>  Building the tree without a <tt>/usr/obj</tt> directory
is not supported.

</ul>
It is important to carefully follow the instructions when 
<a href="#BldGetSrc">fetching</a> and <a href="#Bld">building</a> your
tree.

<a name="ProbIPv6"></a>
<h3>5.11.3 - My IPv6-less system doesn't work!</h3>
Yes.
Please do not make modifications to the base system that you don't
understand the implications of.
One "little" change in the kernel can have very large impact to the
entire rest of the system.
Please re-read <a href="#Why">this</a>.


<a name="ProbObj"></a>
<h3>5.11.4 - Oops! I forgot to make the <tt>/usr/obj</tt> directory
first!</h3>

By doing a "make build" before doing a "make obj", you will end up with
the object files scattered in your <tt>/usr/src</tt> directory.
This is a bad thing.
If you wish to try to avoid re-fetching your entire src tree again, you
can try the following to clean out obj files:
<pre>
    # <b>cd /usr/src</b>
    # <b>find . -type l -name obj | xargs rm</b>
    # <b>make cleandir</b>
    # <b>rm -rf /usr/obj/*</b>
    # <b>make obj</b>
</pre>

<a name="ProbObjPt"></a>
<h3>5.11.5 - Tip: Put <tt>/usr/obj</tt> on its own partition</h3>
If you build often, you may find it faster to put <tt>/usr/obj</tt>
on its own partition.
The benefit is simple, it is typically faster to:
<pre>
    # <b>umount /usr/obj</b>
    # <b>newfs <i>YourObjPartition</i></b>
    # <b>mount /usr/obj</b>
</pre>
than to "rm -rf /usr/obj/*".

<a name="ProbSKIPDIR"></a>
<h3>5.11.6 - How do I not build parts of the tree?</h3>
Sometimes, you may wish to not build certain parts of the tree,
typically because you have installed a replacement for an included
application from packages, or wish to make a "smaller" release for 
whatever reason. 
The solution to this is to use the SKIPDIR option of 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=mk.conf&amp;sektion=5">/etc/mk.conf</a>.

<p>
Note: it is possible to make a broken system this way.
The results of this option are not supported by the OpenBSD project.

<a name="ProbMoreInfo"></a>
<h3>5.11.7 - Where can I learn more about the build process?</h3>
Here are some other resources:
<ul>
<li><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=release&amp;sektion=8">release(8)</a>
<li><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=afterboot&amp;sektion=8#COMPILING+A">afterboot(8)</a>
<li><a href="http://www.openbsd.org/cgi-bin/man.cgi?query=mk.conf&amp;sektion=5">mk.conf(5)</a>
<li><a href="http://www.openbsd.org/cgi-bin/cvsweb/src/Makefile"><tt>/usr/src/Makefile</tt></a>
<li><a href="../stable.html">Patch Branches</a> (<i>-stable</i>)
<li>(for X) <tt>/usr/X11R6/README</tt> on your installed system

</ul>

<a name="NoSnaps"></a>
<h3>5.11.8 - I didn't see any snapshots on the FTP site. Where
did they go?</h3>

<p>
Snapshots may be removed as they become old (or no longer relevant) or 
near the time of a new <i>-release</i>.

<a name="NewCompiler"></a>
<h3>5.11.9 - How do I bootstrap a newer version of the compiler
(<i>gcc</i>)?</h3>

You should really just <a href="#BldBinary">install the latest
snapshot</a>.

<p>
OpenBSD now supports two compilers in-tree, gcc v3.3.5 used by most
platforms, but also gcc v2.95.3 used by a few platforms which haven't
been converted yet, or may never be converted due to lack of gcc3
support or poor gcc3 performance.

<p>
The two compilers are in different parts of the tree:
<ul>
<li>gcc3: <tt>/usr/src/gnu/usr.bin/gcc</tt>
<li>gcc2: <tt>/usr/src/gnu/egcs/gcc</tt>
</ul>

<p>
Because upgrading a compiler is a bit of a chicken-and-egg problem,
changes to the in-tree compiler require a little extra attention.
You have to build the compiler twice -- the first build produces a
compiler that generates new code but runs with code generated by the old
compiler, the second build makes it a completely new compiler.
In general, you'll want to perform the following procedure:

<pre>
    <b>If your platform uses gcc 2.95.3:</b>
       # rm -r /usr/obj/gnu/egcs/gcc/*
       # cd /usr/src/gnu/egcs/gcc
        <i>- or -</i>
    <b>If your platform uses gcc 3.3.5:</b>
       # rm -r /usr/obj/gnu/usr.bin/gcc/*
       # cd /usr/src/gnu/usr.bin/gcc

    <b>Common build procedure for v3.3.5 or v2.95.3</b>
    # make -f Makefile.bsd-wrapper clean
    # make -f Makefile.bsd-wrapper obj
    # make -f Makefile.bsd-wrapper depend
    # make -f Makefile.bsd-wrapper
    # make -f Makefile.bsd-wrapper install
    # make -f Makefile.bsd-wrapper clean
    # make -f Makefile.bsd-wrapper depend
    # make -f Makefile.bsd-wrapper
    # make -f Makefile.bsd-wrapper install
</pre>

<p>
And then run a normal <a href="#BldUserland">make build</a>.

<a name="UpdateEtc"></a>
<h3>5.11.10 - What is the best way to update <tt>/etc</tt>, <tt>/var</tt>,
and <tt>/dev</tt>?</h3>

<p>As a policy, software in the OpenBSD tree does not modify files in
<tt>/etc</tt> automatically.
This means it is <i>always</i> up to the administrator to make the
necessary modifications there.
Upgrades are no exception.
To update files in these directories, first determine what changes have
occurred to the base (distribution) files, and then manually reapply
these changes.

<p>
For example, to see the files in the tree that have changed most
recently, do a:

<pre>
    # cd /usr/src/etc
    # ls -lt |more
</pre>

<!-- XXXversion -->
<p>To see all the changes in <tt>/etc</tt> between arbitrary versions of
OpenBSD, you can use <a href="../anoncvs.html">CVS</a>.
For example, to see the changes between 4.2 and 4.3 do a:

<pre>
    # cd /usr/src/etc
    # cvs diff -u -rOPENBSD_4_2 -rOPENBSD_4_3
</pre>

To see the changes between 4.3 and <i>-current</i> ("HEAD"), use:
<pre>
    # cd /usr/src/etc
    # cvs diff -u -rOPENBSD_4_3 -rHEAD
</pre>

The 
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=MAKEDEV&amp;sektion=8&amp;arch=i386">/dev/MAKEDEV</a>
script is not updated automatically as part of the make build process,
however it is installed as as part of a <a href="#BldBinary">binary
upgrade</a>.
As a general rule, it is a good idea to copy (if needed) and run this
script from your source tree when performing an upgrade:

<pre>
    # cd /dev
    # cp /usr/src/etc/etc.`machine`/MAKEDEV ./
    # ./MAKEDEV all
</pre>

<p>
Once you have identified the changes, reapply them to your local tree,
preserving any local configuration you may have done.

<p>
Typical <tt>/etc</tt> changes to watch out for between releases include:

<ul>
<li>Additions to <tt>/etc/protocols</tt> and <tt>/etc/services</tt></li>
<li>New sysctls (see <tt>/etc/sysctl.conf</tt>)</li>
<li>Changes to the default cron jobs. See <tt>/etc/daily</tt>,
  <tt>/etc/weekly</tt>, <tt>/etc/monthly</tt>, and <tt>/etc/security</tt>
<li>All rc scripts, including netstart</li>
<li>Device changes, see above
<li>File hierarchy changes in <tt>/etc/mtree</tt>, see
  <a href="#Hierarchy">below</a>
<li>New users (<tt>/etc/passwd</tt>) and groups (<tt>/etc/group</tt>)
</ul>

<!-- XXXversion -->
These changes are summarized in
<a href="upgrade43.html">upgrade43.html</a> (for going to 4.3-release)
or <a href="current.html">current.html</a> (for going
to <i>-current</i>).


<a name="Hierarchy"></a>
<h3>5.11.11 - Is there an easy way to make all the file hierarchy changes?</h3>

<p>
From time to time, files or directories are added to, or removed from
the file
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=hier&amp;sektion=7">hierarchy</a>.
Also, ownership information for portions of the filesystem may change.
An easy way to ensure that your file hierarchy is up-to-date is to use
the
<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=mtree&amp;sektion=8">mtree(8)</a>
utility.

<p>
First, fetch the latest source, then do the following:

<pre>
    # cd /usr/src/etc/mtree
    # install -c -o root -g wheel -m 600 special /etc/mtree
    # install -c -o root -g wheel -m 444 4.4BSD.dist /etc/mtree
    # mtree -qdef /etc/mtree/4.4BSD.dist -p / -u
</pre>

<p>
Your file hierarchy should now be up to date.

<a name="ProbXComp"></a>
<h3>5.11.12 - Can I cross-compile?  Why not?</h3>
Cross-compiling tools are in the system, for use by developers bringing
up a new platform.
However, they are not maintained for general use.

<p>
When the developers bring up support for a new platform, one of the
first big tests is a native-build.
Building the system from source puts considerable load on the OS and
machine, and does a very good job of testing how well the system really
works.
For this reason, OpenBSD does all the build process on the platform the
build is being used for, also known as "native building".
Without native building, it is much more difficult to be sure that 
the various platforms are actually running reliably, and not just
booting.

<p>
<font color= "#0000e0">
<a href= "index.html">[FAQ Index]</a>
<a href= "faq4.html">[To Section 4 - Installation Guide]</a>
<a href= "faq6.html">[To Section 6 - Networking]</a>
</font>

<p>
<hr>
<a href= "index.html"><img height= "24" width= "24" src= "../images/back.gif" border= "0" alt= "[back]"></a>
<a href= "mailto:www@openbsd.org">www@openbsd.org</a>
<br>
<small>$OpenBSD: faq5.html,v 1.164 2008/05/24 03:28:14 nick Exp $</small>
</body>
</html>
